Create digital receipts
Merchants can switch their tax invoices or receipts from paper to digital format in accordance with UAE's TAX INVOICE guideline requirements. Customers get digital receipt which is easier to retrieve and store.
API URL
UAT : https://uat.test2pay.com/sgs/api/digitalReceipt/createOrder
Production : https://api.payby.com/sgs/ap/digitalReceipt/createOrder
Request
Http Header
Attributes
Content-Language String
The language in which the response message will be used, currently only English is supported.
Example value: en
Maximum length: 10
Content-Type String Required
The media type. Required for operations with a request body. The value is application/<format>, where format is json.
Example value: application/json
sign String Required
Requests should be signed using private-key cryptography. This allows the payment gateway to verify that an incoming request is really from your application.
Partner-Id String Required
The merchant id of your account.
Example value: 200001200101
Maximum length: 12
Http Body
requestTime Timestamp Required
Request time of the order. If the request time is more than 15 minutes away from the current time, the request will be rejected. This parameter is used to prevent repeated requests for orders that should have been cancelled due to timeouts.
Example value: 1581493898000
bizContent Object
The attributes are:
receiverEmail String
The customer's email to receive digital receipt.
Example value: customer@email.com
Maximum length:
200receiverMobileNumber String
The customer's mobile number to identify his or her member id in PayBy. The customer will receive a message with receipt information in the PayBy app.
Example value: +971-585800000
Maximum length:
32memberId String
The customer's PayBy member ID. The customer will receive a message with receipt information in the PayBy app.
Example value: 10000000011
Maximum length:
12
Note: For the above three parameters, at least one parameter should be passed to specify the receiver. And
receiverMobileNumberandmemberIdcannot be passed at the same time.
receipt String Required
The content of receipt, the attributes are:
type String Required
If you pass
Y, the receipt will showTax Invoiceon it. If you passN, the receipt will not showTax Invoiceon it.Example value: Y
name String
The store name.
Maximum length:
200address String
The store address.
Maximum length:
200tel String
The store contact number.
Maximum length:
200email String
The store contact number.
Maximum length:
200trn String
The merchant's Tax Registration Number.
Example value: 100285640700001
Maximum length:
15receiptNo String Required
The number of this receipt in the merchant's system. Note that the number should be unique, and for different receipts the same receipt number cannot be passed.
Maximum length:
200date Timestamp Required
The date and the time the receipt generated.
Example value: 1581493898000
goodsList List
The attibutes of each item are:
id String
The item's id.
Example value: New Apple iPhone 13 Pro (128GB) - Sierra Blue
Maximum length:
200name1 String Required
The item's name or description.
Maximum length:
200.name2 String
You may pass the item's name in another language.
Maximum length:
200.quantity String
The quantity of this item the customer purchased.
Maximum length:
200.amount Money Required
The unit price of this item.
Maximum length:
200.count Integer
Total quantity of all items.
Maximum value:
100,000.totalBeforeVat Money Required
The payable amount before tax.
vatAmount Money Required
The tax amount.
vatRate Decimal Required
The tax rate. For the rate of 5%, pleasse pass
5.Minimum value:
0Maximum value:
100totalAmount Money Required
The payable amount after tax.
store String
The addtional information of the store.
Maximum length:
200counter String
On which counter the payment was made.
Maximum length:
200pos String
On which POS machine the payment was made.
Maximum length:
200cashier String
Which cashier collected the money when the payment was made. Pass the id or name of the cashier.
Maximum length:
200paymentChannel String
The payment method the customer used when the payment was made.
Maximum length:
200paymentId List
The order number or payment order number. Several order numbers can be passed.
Maximum length of each payment id:
32payAmount Money
The amount paid by the customer.
changeAmount Money
Change amount given by cashier to customer.
refundNo String
If the transaction needs to be refunded, this number can be used to identify the original transaction.
Maximum length:
200notes String
Merchant's notes for the transaction.
Maximum length:
200count Integer
Total quantity of all items.
Maximum value:
100,000
Request sample
Http Header
{
"Content-Language": "en",
"Content-Type": "application/json",
"sign": "XH+aYU46pRZkt2b85i5+imVnIbgxo6bRQjKVL6iZGFfY4HUOtx0/T0Hu1WFAdHG1KlAOhCDP5bPSCvHxYFsdL8ZwNAf1EMKEr47MObQTGUTn2VQ6JnxbWC+mb7LCwnCD9tcnMY0Zx4d+oC7jvtkm1SsRDDcmdMsHBUQqWlIxe5HJmIDPUjNJ9dP9D+jYXUW2BPHF4dRLGxUqyUCq6bDl2WANwl8v8Etz6EBhgzXjicvRwzCfBsz/EgCBF04OfAEuvJ+Z5wJ4xGnPfHJtIW2K/msGLKvUeZ1SXCBlsoRm7k42FcxLVfmRczRLtxWRTKuYfU3H31iYvusAE9j+RDEySw==",
"Partner-Id": "200000000888"
}
Http Body
{
"bizContent":{
"receipt":{
"address":"TCA,Abu Dhabi",
"cashier":"Sajjad Ajij",
"changeAmount":{
"amount":0,
"currency":"AED"
},
"count":2,
"counter":"6",
"date":1631930376223,
"email":"cutomercareauh@ae.lulumea.com",
"goodsList":[
{
"amount":{
"amount":13.2,
"currency":"AED"
},
"id":"9947345013207",
"name1":"Norwegian Salmon Steak",
"name2":"ستيك السلمون النرويجي",
"quantity":1
},
{
"amount":{
"amount":2,
"currency":"AED"
},
"id":"99473450132018",
"name1":"Coca cola 350ml",
"name2":"كوكا كولا 350 مل",
"quantity":5
}
],
"name":"LuLu Express Fresd Market",
"notes":"Keep bill for exchange within 7 days.Valid only at issued store.*T&C Apply.Thanks you for shopping. Shop online at www.luluhypermarket.com",
"payAmount":{
"amount":23.2,
"currency":"AED"
},
"paymentChannel":"CASH",
"pos":"2",
"receiptNo":"534298",
"refundNo":"662142002053429820210730153140",
"store":"2142",
"tel":"02 3090550",
"totalAmount":{
"amount":22.3,
"currency":"AED"
},
"totalBeforeVat":{
"amount":22.3,
"currency":"AED"
},
"trn":"100228723100003",
"type":"Y",
"vatAmount":{
"amount":1.1,
"currency":"AED"
},
"vatRate":5
},
"receiverEmail":"testdemo@payby.com",
"receiverMobileNumber":"+971-585660747"
},
"requestTime":1631930376223
}
Response
Http Header
sign String Required
When PayBy sends response, PayBy will use its own private key to sign the message, and the merchant uses PayBy 's public key to verify the signature. If the verification is passed, it proves that the response was sent by PayBy and not faked by others.
Http Body
head
Attributes
applyStatus Enum Required
The result of the request. The possible values are:
SUCCESS- Application successful.FAIL- Application failed. Check thecodeandmsgfor exact reason.ERROR- Application error. The signature verification failed. Please check whether the private key used for the signature and the public key uploaded on the PayBy portal are one key pair.code String Required
Response Codes.
Example value: 0
msg String
Description of this code.
traceCode String
No special meaning, PayBy internally used to locate the error.
body
Notice : Body is returned only when applystatus = success, and code = 0.
If applystatus = error or failed; or applystatus = success, code !=0 , that indicates an error. Please check errors and try again.
receiptOrder Object
The attributes are:
receiverEmail String
The customer's email to receive digital receipt.
Example value: customer@email.com
Maximum length:
200memberId String
The customer's PayBy member ID. The customer will receive a message with receipt information in the PayBy app.
Example value: 10000000011
Maximum length:
12receiverMobileNumber String
The customer's mobile number to identify his or her member id in PayBy. The customer will receive a message with receipt information in the PayBy app.
Example value: +971-585800000
Maximum length:
32orderNo String
The customer's PayBy member ID. The customer will receive a message with receipt information in the PayBy app.
Example value: 10000000011
Maximum length:
12partnerMid String
The customer's PayBy member ID. The customer will receive a message with receipt information in the PayBy app.
Example value: 10000000011
Maximum length:
12receipt Object
The content of receipt, the attributes are:
type String Required
If you pass
Y, the receipt will showTax Invoiceon it. If you passN, the receipt will not showTax Invoiceon it.Example value: Y
name String
The store name.
Maximum length:
200address String
The store address.
Maximum length:
200tel String
The store contact number.
Maximum length:
200email String
The store contact number.
Maximum length:
200trn String
The merchant's Tax Registration Number.
Example value: 100285640700001
Maximum length:
15receiptNo String Required
The number of this receipt in the merchant's system. Note that the number should be unique, and for different receipts the same receipt number cannot be passed.
Maximum length:
200date Timestamp Required
The date and the time the receipt generated.
Example value: 1581493898000
goodsList List
The attibutes of each item are:
id String
The item's id.
Example value: New Apple iPhone 13 Pro (128GB) - Sierra Blue
Maximum length:
200.name1 String Required
The item's name or description.
Maximum length:
200.name2 String
You may pass the item's name in another language.
Maximum length:
200.quantity String
The quantity of this item the customer purchased.
Maximum length:
200.amount Money Required
The unit price of this item.
Maximum length:
200.
count Integer
Total quantity of all items.
Maximum value:
100,000.totalBeforeVat Money Required
The payable amount before tax.
vatAmount Money Required
The tax amount.
vatRate Decimal Required
The tax rate. For the rate of 5%, pleasse pass
5.Minimum value:
0Maximum value:
100totalAmount Money Required
The payable amount after tax.
store String
The addtional information of the store.
Maximum length:
200counter String
On which counter the payment was made.
Maximum length:
200pos String
On which POS machine the payment was made.
Maximum length:
200cashier String
Which cashier collected the money when the payment was made. Pass the id or name of the cashier.
Maximum length:
200paymentChannel String
The payment method the customer used when the payment was made.
Maximum length:
200paymentId List
The order number or payment order number.
Maximum length of each payment id:
32payAmount Money
The amount paid by the customer.
changeAmount Money
Change amount given by cashier to customer.
refundNo String
If the transaction needs to be refunded, this number can be used to identify the original transaction.
Maximum length:
200notes String
Merchant's notes for the transaction.
Maximum length:
200
Response sample
Http Header
{
"sign": "kjQXk2LcDf2l+3VH3MQaY8UjCEVyvOe8QWHngRm4OsFEwjMXj6uIBcs3x7ZWgkNYG0i9Z2/bFRXfIqVcBr5JHp+/hvMkqkw5UL7ps+1pmV8X+KDo9ReFGlS0ZOax1u5QKgfPvFCH8dR/Qa8dtyk2I6kElMQybQtAKO+4wlafnPQiSVVjYw2MI7r2Or8Rdrmjs4f5hlZjo0bv3uBwWotUE0EshhdZ73DT4puW9CQc02n2/wDxdnHK+3RTn2/LuYWQnRsTZcnNmTeR9zYuFP2vIw+Zoj2+pa3sc2vqqPHoLbZc8LofTauY4+B+B5LXtjWQDp8663oNNK87kNn1SM4m6g=="
}
Http Body
{
"body":{
"receiptOrder":{
"memberId":"100000329946",
"orderNo":"911631930376004613",
"partnerMid":"200000030907",
"receipt":{
"address":"TCA,Abu Dhabi",
"cashier":"Sajjad Ajij",
"changeAmount":{
"amount":0,
"currency":"AED"
},
"count":2,
"counter":"6",
"date":1631930376223,
"email":"cutomercareauh@ae.lulumea.com",
"goodsList":[
{
"amount":{
"amount":13.2,
"currency":"AED"
},
"id":"9947345013207",
"name1":"Norwegian Salmon Steak",
"name2":"ستيك السلمون النرويجي",
"quantity":1
},
{
"amount":{
"amount":2,
"currency":"AED"
},
"id":"99473450132018",
"name1":"Coca cola 350ml",
"name2":"كوكا كولا 350 مل",
"quantity":5
}
],
"name":"LuLu Express Fresd Market",
"notes":"Keep bill for exchange within 7 days.Valid only at issued store.*T&C Apply.Thanks you for shopping. Shop online at www.luluhypermarket.com",
"payAmount":{
"amount":23.2,
"currency":"AED"
},
"paymentChannel":"CASH",
"pos":"2",
"receiptNo":"534298",
"refundNo":"662142002053429820210730153140",
"store":"2142",
"tel":"02 3090550",
"totalAmount":{
"amount":22.3,
"currency":"AED"
},
"totalBeforeVat":{
"amount":22.3,
"currency":"AED"
},
"trn":"100228723100003",
"type":"Y",
"vatAmount":{
"amount":1.1,
"currency":"AED"
},
"vatRate":5
},
"receiverEmail":"testdemo@payby.com",
"receiverMobileNumber":"+971-585660747"
}
},
"head":{
"applyStatus":"SUCCESS",
"code":"0",
"msg":"SUCCESS",
"success":true,
"traceCode":"572147"
}
}